<!DOCTYPE html>
<html>
<head>
<title>ProFTPD module mod_statcache</title>
</head>

<body bgcolor=white>

<hr>
<center>
<h2><b>ProFTPD module <code>mod_statcache</code></b></h2>
</center>
<hr><br>

<p>
The <code>mod_statcache</code> module is designed to cache the results
of <code>stat(2)</code> and <code>lstat(2)</code> calls in shared memory,
so that the results can be shared among multiple session processes.  On
a busy server, especially one handling many directory listings, these
<code>stat(2)</code>/<code>lstat(2)</code> calls can add quite a bit of
overhead.

<p>
This module is contained in the <code>mod_statcache.c</code> file for
ProFTPD 1.3.<i>x</i>, and is not compiled by default.  Installation
instructions are discussed <a href="#Installation">here</a>.  More examples
of <code>mod_statcache</code> usage can be found <a href="#Usage">here</a>.

<p>
The most current version of <code>mod_statcache</code> is distributed with the
ProFTPD source code.

<h2>Author</h2>
<p>
Please contact TJ Saunders &lt;tj <i>at</i> castaglia.org&gt; with any
questions, concerns, or suggestions regarding this module.

<h2>Directives</h2>
<ul>
  <li><a href="#StatCacheCapacity">StatCacheCapacity</a>
  <li><a href="#StatCacheControlsACLs">StatCacheControlsACLs</a>
  <li><a href="#StatCacheEngine">StatCacheEngine</a>
  <li><a href="#StatCacheMaxAge">StatCacheMaxAge</a>
  <li><a href="#StatCacheTable">StatCacheTable</a>
</ul>

<h2>Control Actions</h2>
<ul>
  <li><a href="#statcache"><code>statcache</code></a>
</ul>

<p>
<hr>
<h3><a name="StatCacheCapacity">StatCacheCapacity</a></h3>
<strong>Syntax:</strong> StatCacheCapacity <em>count</em><br>
<strong>Default:</strong> <em>StatCacheCapacity 5000</em><br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later

<p>
The <code>StatCacheCapacity</code> directive configures the <i>capacity</i>
of the cache, <i>i.e.</i> the maximum number of cache entries.  By default,
<code>mod_statcache</code> allocates space for 5000 cache entries.

<p>
The <em>count</em> value be 10 or greater.  The configured <em>count</em>
is handled as a <i>hint</i>; the actual allocated capacity may be rounded up
to the nearest multiple of the internal block sizes.

<p>
<hr>
<h3><a name="StatCacheControlsACLs">StatCacheControlsACLs</a></h3>
<strong>Syntax:</strong> StatCacheControlsACLs <em>actions|&quot;all&quot; &quot;allow&quot;|&quot;deny&quot; &quot;user&quot;|&quot;group&quot; list</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later

<p>
The <code>StatCacheControlsACLs</code> directive configures access lists of
<em>users</em> or <em>groups</em> who are allowed (or denied) the ability to
use the <em>actions</em> implemented by <code>mod_statcache</code>. The default
behavior is to deny everyone unless an ACL allowing access has been explicitly
configured.

<p>
If &quot;allow&quot; is used, then <em>list</em>, a comma-delimited list
of <em>users</em> or <em>groups</em>, can use the given <em>actions</em>; all
others are denied.  If &quot;deny&quot; is used, then the <em>list</em> of
<em>users</em> or <em>groups</em> cannot use <em>actions</em> all others are
allowed.  Multiple <code>StatCacheControlsACLs</code> directives may be used to
configure ACLs for different control actions, and for both users and groups.

<p>
The <em>action</em> provided by <code>mod_statcache</code> is
<a href="#statcache">&quot;statcache&quot;</a>.

<p>
Examples:
<pre>
  # Allow only user root to examine cache stats
  StatCacheControlsACLs all allow user root
</pre>

<p>
<hr>
<h3><a name="StatCacheEngine">StatCacheEngine</a></h3>
<strong>Syntax:</strong> StatCacheEngine <em>on|off</em><br>
<strong>Default:</strong> <em>StatCacheEngine off</em><br>
<strong>Context:</strong> server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code><br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later

<p>
The <code>StatCacheEngine</code> directive enables or disables the module's
caching of <code>stat(2)</code> and <code>lstat(2)</code> calls.

<p>
<hr>
<h3><a name="StatCacheMaxAge">StatCacheMaxAge</a></h3>
<strong>Syntax:</strong> StatCacheMaxAge <em>positive-cache-age [negative-cache-age]</em><br>
<strong>Default:</strong> <em>StatCacheMaxAge 5</em><br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later

<p>
The <code>StatCacheMaxAge</code> directive configures how long the
<code>mod_statcache</code> module will keep the <code>stat(2)</code> or
<code>lstat(2)</code> results cached for a given path.  By default,
<code>mod_statcache</code> will cache results for 5 seconds (and will
cache <i>failed</i> <code>stat(2)</code>/<code>lstat(2)</code> calls for
1 second).

<p>
If you configure a single age parameter, then that value will be used for
both positive and negative cache entries.  Thus:
<pre>
  StatCacheMaxAge 300
</pre>
will cache successful <em>and</em> failed
<code>stat(2)</code>/<code>lstat(2)</code> calls for 5 minutes (300 seconds).

<p>
To disable caching of failed <code>stat(2)</code>/<code>lstat(2)</code> calls
entirely, use a <em>negative-cache-age</em> value of zero, <i>e.g.</i>:
<pre>
  # Cache lookups for 60 seconds, and do not cache failed lookups
  StatCacheMaxAge 60 0
</pre>

<p>
<hr>
<h3><a name="StatCacheTable">StatCacheTable</a></h3>
<strong>Syntax:</strong> StatCacheTable <em>path</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later

<p>
The <code>StatCacheTable</code> directive configures a <em>path</em> to a file
that <code>mod_statcache</code> uses for handling its cache data.  The given
<em>path</em> must be an absolute path.  <b>Note</b>: this directive is
<b>required</b> for <code>mod_statcache</code> to function.  It is recommended
that this file <b>not</b> be on an NFS mounted partition.

<p>
Note that statcache data <b>is not</b> kept across daemon stop/starts.  That is,
once <code>proftpd</code> is shutdown, all current statcache data is lost.

<p>
<hr>
<h2>Control Actions</h2>

<p>
<hr>
<h3><a name="statcache"><code>statcache</code></a></h3>
<strong>Syntax:</strong> ftpdctl statcache <em>info|dump</em><br>
<strong>Purpose:</strong> Display statcache information<br>

<p>
The <code>statcache</code> action is used to display cache statistics about
the statcache data maintained by <code>mod_statcache</code>.  For example:
<pre>
  # ftpdctl statcache info
  ftpdctl:  hits 773, misses 67: 92.0% hit rate
  ftpdctl:    expires 22, rejects 0
  ftpdctl:  current count: 1 (of 5000) (0.0% usage)
  ftpdctl:  highest count: 45 (of 5000) (0.9% usage)
</pre>
To dump out the entire cache contents (not recommended on a busy server),
you can use:
<pre>
  # ftpdctl statcache dump
</pre>

<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_statcache</code> module is distributed with ProFTPD.  For
including <code>mod_statcache</code> as a statically linked module, use:
<pre>
  $ ./configure --with-modules=mod_statcache
</pre>
To build <code>mod_statcache</code> as a DSO module:
<pre>
  $ ./configure --enable-dso --with-shared=mod_statcache
</pre>
Then follow the usual steps:
<pre>
  $ make
  $ make install
</pre>

<p>
For those with an existing ProFTPD installation, you can use the
<code>prxs</code> tool to add <code>mod_statcache</code>, as a DSO module, to
your existing server:
<pre>
  $ prxs -c -i -d mod_statcache.c
</pre>

<p>
<b>Note</b>: Use of the <code>mod_statcache</code> module <b>will</b>
interfere with the <code>mod_vroot</code> and <code>mod_quotatab</code>
modules.

<p>
<hr>
<h2><a name="Usage">Usage</a></h2>

<p>
The <code>mod_statcache</code> module works by allocating a SysV shared
memory segment.  The different <code>proftpd</code> session processes
then attach to that shared memory segment so that they can share statcache
results.

<p>
Example configuration:
<pre>
  &lt;IfModule mod_statcache.c&gt;
    StatCacheEngine on
    StatCacheTable /var/run/proftpd/statcache.tab
  &lt;/IfModule&gt;
</pre>

<p>
<hr>
<font size=2><b><i>
&copy; Copyright 2013-2017 TJ Saunders<br>
 All Rights Reserved<br>
</i></b></font>
<hr>

</body>
</html>
